[COPYRIGHT © 2024 RIBBON COMMUNICATIONS OPERATING COMPANY, INC. ALL RIGHTS RESERVED]: #
# Call Statistics
In this quickstart we will cover the basics of retrieving call statistics with the Javascript SDK. Code snippets will be used to demonstrate this feature, and together these snippets will form a working demo application that can be viewed at the end.
## The need to collect & target audience
Call statistics can be extremely useful to help with debugging various call-related issues in the field. Collecting these statistics may also serve as a basis for some application features. For example, they can be used for displaying the health status of a live call as part of an application's monitoring panel.
Obtaining call statistics is a mid-call operation, therefore, there must be an established call in order to start collecting statistics. For this tutorial, we will assume you're familiar with making and establishing calls. Otherwise, please see [Voice and Video Calls Quickstart](Voice%20and%20Video%20Calls).
The call statistics we're about to capture in this tutorial are low level stats and won't be necessarily appropriate for the end users who make the calls. This tutorial is targeted for developers of call applications, and recommends a way on how to capture this data for call quality analysis.
## Requirements & the returned stats
Collecting Call statistics is done by invoking the [`call.getStats`](https://ribboncommunications.github.io/webrtc-js-sdk/docs/#callgetstats) API.
At a minimum one must provide the `callId` associated with current call. This will return statistics about the call itself.
If a `trackId` is also provided, it can be used to obtain a more specific report (i.e. statistics about the track itself within that active call).
The supplied `trackId` may refer to locally created media tracks or remote tracks.
The returned statistics come from the WebRTC statistics monitoring model in the form of a RTCStatsReport. For further details on such report, see [RTCStatsReport](https://developer.mozilla.org/en-US/docs/Web/API/RTCStatsReport). In addition to RTCStatsReport, there will also be a statistic report coming from the SDK.
Once the `call.getStats` API is invoked, there are two ways of obtaining the results:
- By using the returned Promise object.
- By implementing a handler function which listens to the `call:statsReceived` event.
For simplicity, this tutorial will showcase the first option.
## Collecting Call statistics
Once Call statistics have been collected, they can be further inspected.
For the purpose of collecting such stats, this tutorial is just showing augmented functionality already provided in the [Logging](Logging) tutorial where one can download the collected data, for convenience.
Application developers may choose to download statistics data along with log data.
However, for this tutorial we'll only provide the download of statistics data in order to demonstrate just the Call statistics.
To follow a typical use case, this tutorial binds the Call statistics collection to the lifetime of a single call.
Therefore, the collection of the statistics will start as soon as call is started by either party, and automatically end when either party hangs up the call. For simplicity, the collected stats are stored in an array and each participant in the call will collect its own statistics.
If a new call is started, this tutorial will append its collected stats to the previously collected stats. For this tutorial, we will store the stats for each call in a 2D array. The format of the array will be: `[ [callId, RTCStats], [callId, RTCStats], ... ]`, where `RTCStats` is an array of the collected stats.
```javascript
// Save the call statistics in this array
let callStats = []
```
To keep a simple bound on accumulated data, this array will store up to a maximum of 5 calls worth of statistics.
```javascript
// We'll store only this many calls worth of stats.
const MAX_STATS_LENGTH = 5
```
Once we collect stats for over 5 calls, the stats related to the oldest call will be automatically removed.
Application developers can choose to alter this behaviour of course, based on the application's needs.
## User Interface
To interact with our demo application, we will have a basic UI that allows us to make outgoing calls and respond to incoming calls. The UI will be kept very simple, as it is not the focus of this quickstart, so it will be a straightforward set of elements for user input.
Just like in [Voice and Video Calls Quickstart](Voice%20and%20Video%20Calls), you will need to fill in an appropriate Username & Password and then make a call to another user once subscribed.
We won't cover the widgets associated with these steps as they are covered in their respective tutorial sections.
The only new widget we'll add in this tutorial is a download button, which downloads whatever Call statistics have been accumulated so far.
```html
```
This follows very similar functionality showcased in [Logging Quickstart](Logging) where a download button was provided to get the log data.
Typically, application developers would likely combine these 2 sets of data (logs and call statistics) into one download option.
## Step 1: Making & Answering a Call
For this tutorial, calls are made with audio-only.
We won't go into details on how a call is made/answered, as this is covered in the Voice and Video Calls section.
Because we'll only have a voice call, we will only add a remote container so that each side can hear audio coming from remote peer, once the call is established.
## Step 2: Call Events & Triggering functions
The call events available during the life-cycle of a call are also mentioned in the Voice and Video Calls tutorial (including the ones responsible for rendering the media tracks) and can be referred to from there.
For this tutorial, we chose a few of these events & functions to be the triggers for the start of the Call statistics collection, as well as to mark the end of the collection. For the data collection, we'll use a timer variable which will trigger every 1 second, as follows:
```javascript
// Define our timer variable
let timer
const TIMEOUT_INTERVAL = 1000 // 1 second
function startCallStatsCollection () {
if (timer || !call) {
return
}
log('Starting call stats collection.')
timer = setInterval(retrieveCallStats, TIMEOUT_INTERVAL)
}
function stopCallStatsCollection () {
if (timer) {
log('Stopping call stats collection.')
clearTimeout(timer)
timer = null
}
}
// Implement our Call statistics collection
function retrieveCallStats () {
// Get the stats by invoking the API.
// For this example, we'll only get the stats
// associated with the callId (i.e. no trackId is used as second parameter)
client.call
.getStats(call.id)
.then(stats => {
// Use a boolean to track whether it's a new call's stats
let newCall = true
// Find the stats for the current call using the callId
for (callStat of callStats) {
if (callStat[0] === call.id) {
newCall = false
// Add the stats from the RTCStatsReport Map object to this calls stats
callStat[1].push(...stats.values())
break
}
}
// If the newCall boolean is still true, these stats are for a new call
if (newCall) {
// Before we store this calls stats, remove the oldest call's stats if we are beyond the max collection limit
if (callStats.length === MAX_STATS_LENGTH) {
log('Removing all call statistics associated with oldest call.')
callStats = callStats.slice(1)
}
// Add the stats for this call to the collection of call stats
callStats.push([call.id, [...stats.values()]])
}
})
.catch(error => {
log('Stats collection failed. Error message: ', error.error.message)
clearTimeout(timer)
})
}
```
- Start call stats collection when caller gets a `call:start` event:
```javascript
client.on('call:start', function (params) {
log('Starting call stats collection.')
timer = setInterval(retrieveCallStats, TIMEOUT_INTERVAL) // trigger stats collection every 1 second
}
```
- Start call stats collection when callee answers the call:
```javascript
function answerCall () {
// Retrieve call by callId and answer the call.
...
log('Starting call stats collection.')
timer = setInterval(retrieveCallStats, TIMEOUT_INTERVAL) // trigger stats collection every 1 second
}
```
- Stop the 'local' call stats collection when user hangs up:
```javascript
function endCall () {
log('Stopping call stats collection.')
clearTimeout(timer) // stop stats collection
// Access call by the callId and end the call
...
}
```
- Stop the call stats collection when remote side hangs up.
```javascript
client.on('call:stateChange', function (params) {
// Retrieve call state using params.callId
...
// If the call ended, stop stats collection.
if (call.state === 'Ended') {
log('Stopping call stats collection.')
clearTimeout(timer) // stop stats collection
// Reset callId
...
}
})
```
## Step 3: Save Call Statistics to File
As mentioned earlier, the saving of Call statistics is done in a similar manner to the logs in the Logging tutorial section, and the functionality can be combined to download both types of data.
```javascript
/**
* Function for providing the SDK call statistics to a user via a downloaded file.
* @method downloadCallStats
*/
function downloadCallStats () {
// Convert the saved call stats into a JSON blob.
const blob = new Blob([JSON.stringify(callStats)], { type: 'application/json' })
// Create a button that will save the Blob as a file when clicked.
const button = document.createElement('a')
button.href = URL.createObjectURL(blob)
// Give the file a name.
button.download = Date.now().toString() + '_sdk' + client.getVersion() + '_call_stats.json'
// Auto-click the button.
button.click()
}
```
We can now call the demo application done. We've covered the basics of what is needed to allow a user to collect call statistics.
## Live Demo
Want to try this example for yourself? Click the button below to get started.
_Note: You’ll be sent to an external website._
[COPYRIGHT © 2024 RIBBON COMMUNICATIONS OPERATING COMPANY, INC. ALL RIGHTS RESERVED]: #